---
title: Security Configuration for Consul
owner: Release Integration
---

<strong><%= modified_date %></strong>

This topic describes how to configure security for the Consul agents that run on all Cloud Foundry VMs. Consul secures traffic between VMs by using encryption and mutual authentication.

##<a id='secure'></a>Configure Security ##

To configure security for Consul, you must generate SSL certificates and keys, create Gossip encryption keys, and update your deployment manifest or manifest stub file by including the new keys.

###<a id='generate-certs'></a>Generate SSL Certificates and Keys ###

To generate the certificates and keys that you need for Consul, we recommend that you use the `generate-consul-certs` script in the `scripts` subdirectory of the [cf-release](https://github.com/cloudfoundry/cf-release) repository.

The `generate-consul-certs` script uses [certstrap](https://github.com/square/certstrap) to create a certificate authority (CA) and generate the certificates and keys that Consul needs. It then saves the files to the `./consul-certs` directory.

If you already have a CA that you want to use, you can modify the `generate-consul-certs` script to use your existing CA instead of creating a new one.

###<a id='encrypt-keys'></a>Create Gossip Encryption Keys ###

To create an encryption key for use in the [Serf gossip protocol](https://www.serf.io/docs/internals/gossip.html), provide an arbitrary string value. The consul agent job template transforms the string you provide into a 16-byte Base64-encoded value for consumption by the consul process.

###<a id='stub'></a>Update Your Stub File###

Copy the contents of the files in the `./consul-certs` directory, as well as the value for your Gossip encryption key, into your stub.

## <a id='rotating-certs'></a>Rotate SSL Certificate, Key, and Certificate Authority

Perform the steps below to rotate your SSL certificates, keys, and certificate authorities.

1. Run `bosh deployments` to get a list of all the deployments that BOSH is running.

1. For each deployment:
  1. Run `bosh manifest` (`bosh download manifest` for BOSH v1) to retrieve the manifest file for the deployment.
  1. Append the CA certificate to the `ca_cert` field of your manifest file. Do not remove any existing CA certificates.

        ```
    ...
    properties:
      ...
      consul:
        ...
        encrypt_keys:
        - RANDOM-SECRET-VALUE
        ca_cert: |
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your Old CA Certificate           #######
          ###########################################################
          -----END CERTIFICATE-----
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your New CA Certificate           #######
          ###########################################################
          -----END CERTIFICATE-----
        agent_cert: |
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your Old Agent Certificate        #######
          ###########################################################
          -----END CERTIFICATE-----
        agent_key: |
          -----BEGIN RSA PRIVATE KEY-----
          ###########################################################
          #######           Your Old Agent Key                #######
          ###########################################################
          -----END RSA PRIVATE KEY-----
        server_cert: |
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your Old Server Certificate       #######
          ###########################################################
          -----END CERTIFICATE-----
        server_key: |
          -----BEGIN RSA PRIVATE KEY-----
          ###########################################################
          #######           Your Old Server Key               #######
          ###########################################################
          -----END RSA PRIVATE KEY-----
        ```  
    1. [Deploy Cloud Foundry](./deploy.html) using your updated manifest.

1. After redeploying all deployments with the new CA certificates, you can rotate all the SSL certs and keys. For each deployment:

  1. Replace the old server and agent certificates and keys with the new certificates and keys.

        ```
    ...
    properties:
      ...
      consul:
        ...
        encrypt_keys:
        - RANDOM-SECRET-VALUE
        ca_cert: |
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your Old CA Certificate           #######
          ###########################################################
          -----END CERTIFICATE-----
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your New CA Certificate           #######
          ###########################################################
          -----END CERTIFICATE-----
        agent_cert: |
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your New Agent Certificate        #######
          ###########################################################
          -----END CERTIFICATE-----
        agent_key: |
          -----BEGIN RSA PRIVATE KEY-----
          ###########################################################
          #######           Your New Agent Key                #######
          ###########################################################
          -----END RSA PRIVATE KEY-----
        server_cert: |
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your New Server Certificate       #######
          ###########################################################
          -----END CERTIFICATE-----
        server_key: |
          -----BEGIN RSA PRIVATE KEY-----
          ###########################################################
          #######           Your New Server Key               #######
          ###########################################################
          -----END RSA PRIVATE KEY-----
          ```
  1. [Deploy Cloud Foundry](./deploy.html) using your updated manifest.

  1. Remove your old CA Certificate.

        ```
    ...
    properties:
      ...
      consul:
        ...
        encrypt_keys:
        - RANDOM-SECRET-VALUE
        ca_cert: |
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your New CA Certificate           #######
          ###########################################################
          -----END CERTIFICATE-----
        agent_cert: |
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your New Agent Certificate        #######
          ###########################################################
          -----END CERTIFICATE-----
        agent_key: |
          -----BEGIN RSA PRIVATE KEY-----
          ###########################################################
          #######           Your New Agent Key                #######
          ###########################################################
          -----END RSA PRIVATE KEY-----
        server_cert: |
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your New Server Certificate       #######
          ###########################################################
          -----END CERTIFICATE-----
        server_key: |
          -----BEGIN RSA PRIVATE KEY-----
          ###########################################################
          #######           Your New Server Key               #######
          ###########################################################
          -----END RSA PRIVATE KEY-----
        ```
    1. [Deploy Cloud Foundry](./deploy.html) using your updated manifest.

## <a id='rotating-encryption-key'></a>Rotate Encryption Key

To rotate your encryption key, perform the steps below.

1. In the `encrypt_keys` field of your manifest, insert the new encryption key above the old encryption key. Do not remove old encryption key. 

    ```
    ...
    properties:
      ...
      consul:
        ...
        encrypt_keys:
        - NEW-ENCRYPT-KEY
        - OLD-ENCRYPT-KEY
        ...
   ```

1. Deploy Cloud Foundry using your updated manifest.

1. Remove the old encryption key from your manifest.

    ```
    ...
    properties:
      ...
      consul:
        ...
        encrypt_keys:
        - NEW-ENCRYPT-KEY
        ...
   ```
1. Deploy Cloud Foundry using your updated manifest.
